home *** CD-ROM | disk | FTP | other *** search
/ PC Advisor 2011 May / PC Advisor 190 E.iso / pc / ESSENTIALS / VLC Media Player 1.1 / vlc-1.1.5-win32.exe / sdk / include / vlc / plugins / vlc_events.h < prev    next >
Encoding:
C/C++ Source or Header  |  2010-11-13  |  8.3 KB  |  265 lines
  1. /*****************************************************************************
  2.  * events.h: events definitions
  3.  * Interface used to send events.
  4.  *****************************************************************************
  5.  * Copyright (C) 2007 the VideoLAN team
  6.  * $Id: 50cbc61912b8d051eaf79e3914d5bc417937fcb9 $
  7.  *
  8.  * Authors: Pierre d'Herbemont
  9.  *
  10.  * This program is free software; you can redistribute it and/or modify
  11.  * it under the terms of the GNU General Public License as published by
  12.  * the Free Software Foundation; either version 2 of the License, or
  13.  * (at your option) any later version.
  14.  *
  15.  * This program is distributed in the hope that it will be useful,
  16.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18.  * GNU General Public License for more details.
  19.  *
  20.  * You should have received a copy of the GNU General Public License
  21.  * along with this program; if not, write to the Free Software
  22.  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23.  *****************************************************************************/
  24.  
  25. #ifndef VLC_EVENTS_H
  26. # define VLC_EVENTS_H
  27.  
  28. #include <vlc_arrays.h>
  29. #include <vlc_meta.h>
  30.  
  31. /**
  32.  * \file
  33.  * This file is the interface definition for events
  34.  * (implementation in src/misc/events.c)
  35.  */
  36.  
  37. /*****************************************************************************
  38.  * Documentation
  39.  *****************************************************************************/
  40. /*
  41.  **** Background
  42.  *
  43.  * This implements a way to send and receive event for an object (which can be
  44.  * a simple C struct or less).
  45.  *
  46.  * This is in direct concurrency with the Variable based Callback
  47.  * (see src/misc/variables.c).
  48.  *
  49.  * It has the following advantages over Variable based Callback:
  50.  * - No need to implement the whole VLC_COMMON_MEMBERS in the object,
  51.  * thus it reduce it size. This is especially true for input_item_t which
  52.  * doesn't have VLC_COMMON_MEMBERS. This is the first reason of existence of
  53.  * this implementation.
  54.  * - Libvlc can easily be based upon that.
  55.  * - Existing event are clearly declared (in include/vlc_events.h)
  56.  *
  57.  *
  58.  **** Example usage
  59.  *
  60.  * (vlc_cool_object_t doesn't need to have the VLC_COMMON_MEMBERS.)
  61.  *
  62.  * struct vlc_cool_object_t
  63.  * {
  64.  *        ...
  65.  *        vlc_event_manager_t p_event_manager;
  66.  *        ...
  67.  * }
  68.  *
  69.  * vlc_my_cool_object_new()
  70.  * {
  71.  *        ...
  72.  *        vlc_event_manager_init( &p_self->p_event_manager, p_self, p_a_libvlc_object );
  73.  *        vlc_event_manager_register_event_type(p_self->p_event_manager,
  74.  *                vlc_MyCoolObjectDidSomething, p_e)
  75.  *        ...
  76.  * }
  77.  *
  78.  * vlc_my_cool_object_release()
  79.  * {
  80.  *         ...
  81.  *         vlc_event_manager_fini( &p_self->p_event_manager );
  82.  *         ...
  83.  * }
  84.  *
  85.  * vlc_my_cool_object_do_something()
  86.  * {
  87.  *        ...
  88.  *        vlc_event_t event;
  89.  *        event.type = vlc_MyCoolObjectDidSomething;
  90.  *        event.u.my_cool_object_did_something.what_it_did = kSomething;
  91.  *        vlc_event_send( &p_self->p_event_manager, &event );
  92.  * }
  93.  * */
  94.  
  95.   /*****************************************************************************
  96.  * Event Type
  97.  *****************************************************************************/
  98.  
  99. /* Private structure defined in misc/events.c */
  100. struct vlc_event_listeners_group_t;
  101.  
  102. /* Event manager type */
  103. typedef struct vlc_event_manager_t
  104. {
  105.     void * p_obj;
  106.     vlc_mutex_t object_lock;
  107.     vlc_mutex_t event_sending_lock;
  108.     vlc_object_t *p_parent_object;
  109.     DECL_ARRAY(struct vlc_event_listeners_group_t *) listeners_groups;
  110. } vlc_event_manager_t;
  111.  
  112. /* List of event */
  113. /* Be sure to keep sync-ed with misc/events.c debug name table */
  114. typedef enum vlc_event_type_t {
  115.     /* Input (thread) events */
  116.     vlc_InputStateChanged,
  117.     vlc_InputSelectedStreamChanged,
  118.  
  119.     /* Input item events */
  120.     vlc_InputItemMetaChanged,
  121.     vlc_InputItemSubItemAdded,
  122.     vlc_InputItemSubItemTreeAdded,
  123.     vlc_InputItemDurationChanged,
  124.     vlc_InputItemPreparsedChanged,
  125.     vlc_InputItemNameChanged,
  126.     vlc_InputItemInfoChanged,
  127.     vlc_InputItemErrorWhenReadingChanged,
  128.  
  129.     /* Service Discovery event */
  130.     vlc_ServicesDiscoveryItemAdded,
  131.     vlc_ServicesDiscoveryItemRemoved,
  132.     vlc_ServicesDiscoveryStarted,
  133.     vlc_ServicesDiscoveryEnded
  134. } vlc_event_type_t;
  135.  
  136. /* Event definition */
  137. typedef struct vlc_event_t
  138. {
  139.     vlc_event_type_t type;
  140.     void * p_obj; /* Sender object, automatically filled by vlc_event_send() */
  141.     union vlc_event_type_specific
  142.     {
  143.         /* Input (thread) events */
  144.         struct vlc_input_state_changed
  145.         {
  146.             int new_state;
  147.         } input_state_changed;
  148.         struct vlc_input_selected_stream_changed
  149.         {
  150.             void * unused;
  151.         } input_selected_stream_changed;
  152.  
  153.         /* Input item events */
  154.         struct vlc_input_item_meta_changed
  155.         {
  156.             vlc_meta_type_t meta_type;
  157.         } input_item_meta_changed;
  158.         struct vlc_input_item_subitem_added
  159.         {
  160.             input_item_t * p_new_child;
  161.         } input_item_subitem_added;
  162.         struct vlc_input_item_subitem_tree_added
  163.         {
  164.             input_item_node_t * p_root;
  165.         } input_item_subitem_tree_added;
  166.         struct vlc_input_item_duration_changed
  167.         {
  168.             mtime_t new_duration;
  169.         } input_item_duration_changed;
  170.         struct vlc_input_item_preparsed_changed
  171.         {
  172.             int new_status;
  173.         } input_item_preparsed_changed;
  174.         struct vlc_input_item_name_changed
  175.         {
  176.             const char * new_name;
  177.         } input_item_name_changed;
  178.         struct vlc_input_item_info_changed
  179.         {
  180.             void * unused;
  181.         } input_item_info_changed;
  182.         struct input_item_error_when_reading_changed
  183.         {
  184.             bool new_value;
  185.         } input_item_error_when_reading_changed;
  186.  
  187.         /* Service discovery events */
  188.         struct vlc_services_discovery_item_added
  189.         {
  190.             input_item_t * p_new_item;
  191.             const char * psz_category;
  192.         } services_discovery_item_added;
  193.         struct vlc_services_discovery_item_removed
  194.         {
  195.             input_item_t * p_item;
  196.         } services_discovery_item_removed;
  197.         struct vlc_services_discovery_started
  198.         {
  199.             void * unused;
  200.         } services_discovery_started;
  201.         struct vlc_services_discovery_ended
  202.         {
  203.             void * unused;
  204.         } services_discovery_ended;
  205.  
  206.     } u;
  207. } vlc_event_t;
  208.  
  209. /* Event callback type */
  210. typedef void ( *vlc_event_callback_t )( const vlc_event_t *, void * );
  211.  
  212.  /*****************************************************************************
  213.  * Event manager
  214.  *****************************************************************************/
  215.  
  216. /*
  217.  * p_obj points to the object that owns the event manager, and from
  218.  * which events are sent
  219.  * p_obj is here to give us a libvlc instance
  220.  */
  221. #define vlc_event_manager_init_with_vlc_object(a,b) \
  222.             vlc_event_manager_init( a, b, b )
  223.  
  224. VLC_EXPORT(int, vlc_event_manager_init, ( vlc_event_manager_t * p_em,
  225.                                           void * p_obj, vlc_object_t * ));
  226. #define vlc_event_manager_init(a,b,c) \
  227.             vlc_event_manager_init(a, b, VLC_OBJECT(c))
  228.  
  229. /*
  230.  * Destroy
  231.  */
  232. VLC_EXPORT(void, vlc_event_manager_fini, ( vlc_event_manager_t * p_em ));
  233.  
  234. /*
  235.  * Tells a specific event manager that it will handle event_type object
  236.  */
  237. VLC_EXPORT(int, vlc_event_manager_register_event_type,
  238.                 ( vlc_event_manager_t * p_em, vlc_event_type_t event_type ));
  239.  
  240. /*
  241.  * Send an event to the listener attached to this p_em.
  242.  */
  243. VLC_EXPORT(void, vlc_event_send, ( vlc_event_manager_t * p_em,
  244.                                    vlc_event_t * p_event ));
  245.  
  246. /*
  247.  * Add a callback for an event.
  248.  */
  249. VLC_EXPORT(int, vlc_event_attach, ( vlc_event_manager_t * p_event_manager,
  250.                                     vlc_event_type_t event_type,
  251.                                     vlc_event_callback_t pf_callback,
  252.                                     void *p_user_data,
  253.                                     const char * psz_debug_name ));
  254. #define vlc_event_attach(a, b, c, d) vlc_event_attach(a, b, c, d, #c)
  255.  
  256. /*
  257.  * Remove a callback for an event.
  258.  */
  259. VLC_EXPORT(int, vlc_event_detach, ( vlc_event_manager_t *p_event_manager,
  260.                                     vlc_event_type_t event_type,
  261.                                     vlc_event_callback_t pf_callback,
  262.                                     void *p_user_data ));
  263.  
  264. #endif /* VLC_EVENTS_H */
  265.